docs(cli): models and usage + reference with troubleshooting - #405
Conversation
Fill in the three cli-reference pages from the Warp CLI launch skeleton: - cli/reference: command-line flags with examples, environment variables, full slash-command table (25 commands verified against the CLI command registry), and default keyboard shortcuts sourced from the CLI keybinding definitions. - cli/models-and-usage: /model picker and footer model entry, BYOK via /add-api-key + provider flags (OpenAI/Anthropic/Google), custom model routers in the picker, and cost transparency (footer credits toggle, /cost per-response summary). - cli/troubleshooting: /view-logs bundling and log locations, login troubleshooting, autoupdate behavior with /version and --version, and support links. Co-Authored-By: Oz <oz-agent@warp.dev>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
I'm starting a first review of this pull request. You can view the conversation on Warp. I completed the review and no human review was requested for this pull request. Comment Powered by Oz |
![oz-for-oss[bot]](https://avatars.githubusercontent.com/in/3450139?s=60&v=4){kind=small}
There was a problem hiding this comment.
Overview
This PR replaces placeholder CLI documentation with reference, model/usage, and troubleshooting content. The general structure is solid, but the API-key examples need safer secret-handling guidance before merge.
Concerns
- The
--api-keyexample encourages putting a Warp API key directly in the command line, where it can be captured in shell history or process listings. - The provider-key stdin example uses a plaintext
key.txtfile without warning users to avoid persistent or checked-in secret files.
Security
- Update the API-key examples to prefer
WARP_API_KEYor clearly warn about command-line exposure. - Add a caveat for stdin-based provider keys so users use a secure temporary file or secret-manager output rather than a long-lived plaintext file.
Verdict
Found: 0 critical, 1 important, 1 suggestions
Request changes
Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).
Powered by Oz
| Authenticates with a Warp API key instead of the interactive browser login. Useful on hosts where a browser sign-in is inconvenient. | ||
|
|
||
| ```bash | ||
| warp --api-key YOUR_API_KEY |
There was a problem hiding this comment.
WARP_API_KEY=YOUR_API_KEY warp as the primary example, or add an explicit warning before documenting --api-key.
There was a problem hiding this comment.
Fixed in 1c6b6ae: WARP_API_KEY=YOUR_API_KEY warp is now the primary non-interactive auth example; --api-key stays documented secondarily with a caution that command-line arguments can be captured in shell history and process listings. The troubleshooting sign-in section now also lists the environment variable first.
| The CLI prompts for the key with masked input, so the key never appears in your shell history. When stdin is piped, the key is read from stdin instead: | ||
|
|
||
| ```bash | ||
| warp --set-provider-api-key anthropic < key.txt |
There was a problem hiding this comment.
💡 [SUGGESTION] [SECURITY] The stdin example should warn users not to keep provider keys in a persistent plaintext key.txt file; suggest using a secure temporary file or piping from a secret manager and deleting any local file afterward.
There was a problem hiding this comment.
Fixed in 1c6b6ae: the stdin example now pipes from a secret manager (tool-agnostic placeholder) instead of a persistent key.txt, with a note to avoid plaintext key files and delete any temporary file immediately afterward.
Frontmatter {{WARP_CLI}} tokens are not substituted by the build (Astro's
content layer parses frontmatter outside Vite), so built titles showed the
raw token. Body prose keeps {VARS.WARP_CLI}.
Co-Authored-By: Oz <oz-agent@warp.dev>
Consolidation: the standalone troubleshooting page merges into cli/reference.mdx as a final Troubleshooting section with problem-oriented H3 subsections. Existing H2 anchors (#slash-commands, #keyboard-shortcuts) are unchanged; internal links now point at #updating and #command-line-flags. troubleshooting.mdx is restored to the base-branch stub (the orchestrator removes it at integration). Co-Authored-By: Oz <oz-agent@warp.dev>
hongyi-chen
changed the title
…cli-cli-reference
Follows the base-branch WARP_CLI var value change; body prose picks up the
new name automatically via {VARS.WARP_CLI}.
Co-Authored-By: Oz <oz-agent@warp.dev>
Address review feedback: - Make WARP_API_KEY=... warp the primary non-interactive auth example and document --api-key secondarily with a caution that command-line arguments can be captured in shell history and process listings. - Replace the persistent key.txt stdin example with a tool-agnostic secret-manager pipe and a note against staging keys in plaintext files. Co-Authored-By: Oz <oz-agent@warp.dev>
Reduce product-name density after each page's intro (prefer "the CLI"), vary repeated trailing "See [X]" sentences, and fold two cross-links into their sentences. No structural, factual, heading, or link-target changes. Co-Authored-By: Oz <oz-agent@warp.dev>
Cut the type-to-filter/arrows/Enter sentence from the model picker prose and the keep-typing-to-filter clause from the slash-command intro, per the editorial bar against narrating self-evident UI mechanics. Defaults, exceptions, and lookup tables are unchanged. Co-Authored-By: Oz <oz-agent@warp.dev>
Platform audit: every keybinding registration is identical on macOS and Linux (the only platform-conditional binding is a Windows-only Alt+V paste, which is not documented since no Windows build ships). Input arrives as terminal key events, so Alt shortcuts depend on the host terminal delivering Option as Alt on macOS; add one note to the keyboard shortcuts section instead of per-row annotations. Co-Authored-By: Oz <oz-agent@warp.dev>
Co-Authored-By: Oz <oz-agent@warp.dev>
harryalbert
left a comment
harryalbert
left a comment
There was a problem hiding this comment.
approving to unblock but worth a rewrite of the api keys section because I just merged a change that significantly changes that flow
| {/* TODO(cli-reference): draft per drafts/warp-cli-launch-plan.md — "cli/models-and-usage.mdx" section. Feature-doc content type. */} | ||
|
|
||
| The {VARS.WARP_CLI} documentation for this page is in progress. | ||
| The {VARS.WARP_CLI} gives you the same model options as the Warp app: pick the model that powers your conversations, bring your own provider API keys, route requests through custom model routers, and see what every response costs as you work. |
There was a problem hiding this comment.
was keeping {VARS.WARP_CLI} here intentional?
There was a problem hiding this comment.
Yes, intentional. {VARS.WARP_CLI} works in body prose (real MDX import), but the {{WARP_CLI}} tokens in frontmatter weren't being substituted at build time (Astro's content layer parses frontmatter outside Vite), so built page titles showed the raw token — hence hardcoding just the frontmatter title/description (commits 68bd887/4bed38a) while body prose keeps the variable. Other cli/ pages still using {{WARP_CLI}} frontmatter are base-branch stubs that will need the same treatment at integration.
| {/* TODO(cli-reference): /add-api-key, /clear-provider-api-key, --set-provider-api-key, --clear-provider-api-key; supported providers; cross-link agent-platform/inference/bring-your-own-api-key. */} | ||
| The CLI supports [Bring Your Own API Key (BYOK)](/agent-platform/inference/bring-your-own-api-key/) for OpenAI, Anthropic, and Google models. When you select a model covered by one of your keys, requests are billed through your provider account and don't consume your Warp [credits](/support-and-community/plans-and-billing/credits/). | ||
|
|
||
| To store a key, run `/add-api-key` with one of `openai`, `anthropic`, or `google`: |
There was a problem hiding this comment.
Could you ask an agent to rewrite this section? I just merged this PR which updates the api key flow and makes it a lot better/clearer in-app
There was a problem hiding this comment.
Rewrote in be16142 against the merged /api-keys flow (warpdotdev/warp#14472 + CODE-1930 spec). The section now covers the /api-keys menu: masked set/replace/clear for OpenAI/Anthropic/Google (saving an empty field or Ctrl+X clears), X Premium/SuperGrok connection via browser sign-in, and the Warp credit fallback toggle. Kept --set-provider-api-key/--clear-provider-api-key documented for scripting since the spec explicitly preserves them, with a note that X Premium/SuperGrok is managed only through /api-keys.
| The {VARS.WARP_CLI} documentation for this page is in progress. | ||
| This page is a lookup reference for the {VARS.WARP_CLI}: the flags and environment variables the `warp` command accepts, every slash command available in a session, the default keyboard shortcuts, and fixes for common issues. | ||
|
|
||
| ## Command-line flags |
There was a problem hiding this comment.
probably merged after these docs were written, but there's now also a --fast-forward flag that auto-enables fast forward for TUI conversations (just for the session where that flag was ran)
There was a problem hiding this comment.
Added in be16142 — one naming note: the flag landed as --auto-approve (warpdotdev/warp#14483), matching the TUI's /auto-approve naming; there's no --fast-forward in TuiArgs on master. Documented with the session-scoped behavior: new conversations in that launch start with auto-approve on, still toggleable per conversation, saved settings unchanged.
|
|
||
| | Command | Argument | Description | | ||
| | --- | --- | --- | | ||
| | `/add-api-key` | `<openai\|anthropic\|google>` | Securely store a model-provider API key | |
There was a problem hiding this comment.
this is now just /api-keys (per the comment above)
There was a problem hiding this comment.
Fixed in be16142: the table now lists /api-keys (no argument) in place of /add-api-key, and the BYOK section in models-and-usage documents the new menu.
| | `/agent` | `[prompt]` | Start a new conversation | | ||
| | `/auto-approve` | | Toggle auto-approve for agent actions | | ||
| | `/clear` | `[prompt]` | Clear the transcript and start a new conversation | | ||
| | `/clear-provider-api-key` | `<openai\|anthropic\|google>` | Remove a stored model-provider API key | |
There was a problem hiding this comment.
This no longer exists (per the comment above)
There was a problem hiding this comment.
Removed in be16142. The --clear-provider-api-key command-line flag stays documented since it remains supported (the CODE-1930 spec lists removing the flags as a non-goal) — only the slash command is gone.
…flag Address review feedback on the API key flow change (warpdotdev/warp#14472), which replaced /add-api-key and /clear-provider-api-key with a single inline /api-keys menu: - models-and-usage: rewrite the BYOK section around the /api-keys menu — set/replace/clear provider keys with masked entry, connect or disconnect X Premium/SuperGrok via browser sign-in, and toggle Warp credit fallback. The --set-provider-api-key/--clear-provider-api-key flags stay documented for scripting (they remain supported per the CODE-1930 spec). - reference: swap the /add-api-key and /clear-provider-api-key slash-command rows for /api-keys, and point --set-provider-api-key at the in-session menu. - reference: document the new --auto-approve flag (warpdotdev/warp#14483), which starts new conversations in that launch with auto-approve enabled. Co-Authored-By: Oz <oz-agent@warp.dev>
Remove redundant clauses: drop the repeated launch-default sentence in --auto-approve, the doubled keys-over-credits statement in the fallback bullet, the repeated browser-sign-in rationale in the scripting paragraph, and tighten the /api-keys table row to match the terse row pattern. Co-Authored-By: Oz <oz-agent@warp.dev>
PR #405 consolidated troubleshooting into cli/reference.mdx (its Troubleshooting section) and reset cli/troubleshooting.mdx back to the skeleton stub, leaving the stub published in the sidebar with no sub-PR left to fill it. Remove the stub and its sidebar entry, matching the treatment #423 gives the conversations stub. No inbound links exist to /cli/troubleshooting/ (checked all merged and open cli sub-PR content), so no repoints are needed. Advances the 'delete 4 orphaned stubs' item on the #411 integration checklist. Validation: npm run build green; internal link check 0 broken. Co-authored-by: Oz <oz-agent@warp.dev>
2 participants
Pages changed
src/content/docs/cli/reference.mdx(now includes the Troubleshooting section)src/content/docs/cli/models-and-usage.mdxsrc/content/docs/cli/troubleshooting.mdxis restored to the base-branch stub per the page consolidation (13 → 9); the orchestrator removes that page at integration.Features covered
reference
--resume,--api-key(+WARP_API_KEY),--set-provider-api-key,--clear-provider-api-key,--version,--help(verified against the CLI arg parser)WARP_API_KEY,WARP_TUI_DISABLE_AUTOUPDATE/skill-name/view-logszip bundling + macOS log location~/Library/Logs/warp-cli/; login issues (browser-less device-auth URL + code, "Login failed", wrong account via/logoutincl. web sign-out,--resumerestore failure); updating (background autoupdate applied on next launch,/version+warp --version, env/setting opt-out); getting-help links#slash-commandsand#keyboard-shortcutspreserved for sibling-page links; new#troubleshootinganchor availablemodels-and-usage
/modelpicker + footer model entry (click toggles the same picker); selection persists to the active profile's base model/add-api-key,/clear-provider-api-key+ CLI flags; providers enumerated from code (openai, anthropic, google); masked input; Auto-models-consume-credits note; cross-links to inference/BYOK docs~/.warp/custom_model_routers/definitions as the app (feature ships in default/stable flag set)/costper-response duration + credits summaryThe launch blog claims these two capabilities for the Warp Agent CLI. I verified both against warp master and could not find a shipped CLI path; eng should reconcile before launch. Neither is documented on the page:
ApiKeys.custom_endpointswere populated, but there is no CLI surface to configure an endpoint (the add/edit flow exists only in the app's settings UI), the CLI key commands accept only openai|anthropic|google (no openrouter slug), and the CLI intentionally uses a separate secure-storage namespace from the app (LaunchMode::secure_storage_service_name), so endpoints configured in the Warp app are not visible to the CLI process.If eng lands either capability (or a shared-keychain/import path) before launch, I can add them to models-and-usage with cross-links to agent-platform/inference/custom-inference-endpoint and agent-platform/inference/grok-subscription.
Dropped/unconfirmed
/add-api-keyaccept only openai|anthropic|google; xAI is excluded from the API-key provider list in code./status: dropped — no such command exists in the slash-command registry./copy-debugging-link: dropped — not in the registry; no CLI implementation found on master./fast-forward: dropped — no such slash command in the registry (auto-approve is the shipped toggle; documented under permissions page's scope)./pr-commentsdisplay: dropped — no such slash command in the registry.--list-models/ headless runs: excluded per plan — absent from the CLI arg parser.Notes for reviewers
Ctrl+Palso toggles plans in terminals without keyboard-enhancement support; I documented onlyCtrl+Shift+Pto avoid over-qualifying. Flag if you want both.Suggested reviewer(s): harry, ian (moira for custom routing)
Co-Authored-By: Oz oz-agent@warp.dev